Skip to main content

Network Mode

TanStack Query提供了三种不同的网络模式，用于区分在没有网络连接时Query和Mutation应该如何行为。可以为每个Query/Mutation单独设置此模式，也可以通过查询/突变默认设置全局模式。

由于TanStack Query通常与数据获取库一起用于数据获取，因此默认的网络模式是online（在线）。

Network Mode: online​

网络模式：online（在线）

在此模式下，只有在有网络连接时，查询和突变才会触发。这是默认模式。如果由于没有网络连接而无法进行fetch，则查询将保持在其当前状态（loading、error、success）。此外，还会公开fetchStatus。它可以是以下之一：

  • fetching（正在获取）：queryFn正在执行 - 请求正在进行中。
  • paused（已暂停）：查询未执行 - 它将暂停，直到您重新获得网络连接。
  • idle（空闲）：查询既不获取也不暂停。

isFetching和isPaused是从这个状态派生出来的标志，并为方便起见公开。

请注意，仅检查loading状态可能不足以显示加载动画。如果查询是第一次挂载且没有网络连接，查询可能处于状态：'loading'，但fetchStatus：'paused'。

如果一个查询在你在线时运行，但在fetch仍在进行时你断网了，TanStack Query也会暂停重试机制。暂停的查询将在重新获得网络连接后继续运行。这与refetchOnReconnect（在此模式下默认为true）无关，因为它不是重新获取refetch，而是继续获取continue。如果查询在此期间已被取消cancelled，则不会继续执行。

Network Mode: always​

网络模式：always（始终）

在此模式下，TanStack Query将始终进行fetch，并忽略在线/离线状态。如果您在不需要活动网络连接即可使用查询的环境中使用TanStack Query（例如，只从AsyncStorage中读取数据，或者只需从queryFn返回Promise.resolve(5)），这可能是您想选择的模式。

  • 由于没有网络连接，查询将永远不会暂停。
  • 重试也不会暂停 - 如果查询失败，它将进入错误状态。
  • 在此模式下，默认情况下refetchOnReconnect为false，因为重新连接到网络不再是应该重新获取陈旧查询的好指标。如果需要，仍然可以打开它。

Network Mode: offlineFirst​

网络模式：offlineFirst（优先离线）

该模式是前两个选项之间的折中，TanStack Query将运行queryFn一次，但然后暂停重试。如果您有一个serviceWorker拦截请求以进行缓存（例如在离线优先的PWA中）或者使用Cache-Control标头进行HTTP缓存，那么这将非常有用。

在这些情况下，由于从离线存储/缓存中获取，第一次fetch可能成功。但是，如果缓存未命中，则会发送网络请求并失败，在这种情况下，此模式的行为类似于在线查询 - 暂停重试。

Devtools（开发工具）​

TanStack Query开发工具将显示查询处于暂停状态（如果它们将进行fetch，但没有网络连接）。还有一个切换按钮用于模拟离线行为。请注意，该按钮实际上不会影响您的网络连接（您可以在浏览器开发工具中执行此操作），但它会将OnlineManager设置为离线状态。

Signature​

  • networkMode: 'online' | 'always' | 'offlineFirst'
    • 可选的
    • 默认为 online